package com.magenta.maxoptra.gis;

import java.util.List;

/**
* Project: Maxoptra
* Author: Kirill Sychin
* Date: 23.10.2008 12:17:27
* Copyright (c) 1999-2008 Magenta Corporation Ltd. All Rights Reserved.
* Magenta Technology proprietary and confidential.
* Use is subject to license terms.
*
*/

/**
 * Interface IGeocoding ...
 * <b>WARNING!!!</b> Low-level interface for simple queries and without caching.
 */
public interface IGeocoding extends IGeoProvider {

    /**
     * Search the address by a keyword
     *
     * @param keyword - search phrase
     * @param i       - limit of founded addresses
     * @return list of geo-address objects
     * @throws GeoException -
     *
     */
    List<GeoAddress> findAddressByKeyword(GeoProviderSettings settings, String keyword, int i) throws GeoException;

    /**
     * Search the address by a keyword
     * @param settings
     * @param keyword
     * @return only one variant
     * @throws GeoException
     */
    GeoAddress findBestAddressByKeyword(GeoProviderSettings settings, String keyword) throws GeoException;

    /**
     * Преобразует Адрес в гео-координату. Если данному адресу соответствует несколько координат,
     * тогда будет возвращен список адресов, соответствующих этим координатам.
     *
     *
     * @param address адрес, по которому будут искаться
     * @param resultAddressLimit максимальное количество адресов, которое может быть возвращено методом
     * @return список геоадресов, соответствующих указанному адресу
     * @throws GeoException -
     */
    List<GeoAddress> doForwardGeocoding(GeoProviderSettings settings, GeoAddress address, int resultAddressLimit) throws GeoException;


}
